.. _cmlPmHomeGetSuccess:

cmlPmHomeGetSuccess 
================================
--------------------------------


SYNOPSYS
`````````````
.. code-block:: none

    VT_I4 cmlPmHomeSetSuccess ([in] VT_I4 BoardID, [in] VT_I4 NodeId, [in] VT_I4 Channel, [in] VT_I4 IsSuccess )               

DESCRIPTION
`````````````  

- cmlPmHomeSetSuccess() 함수는 원점 복귀의 성공 여부에 대한 상태를 강제로 설정하는 함수입니다. 
  일반적으로는 원점 복귀 완료 상태는 원점 복귀의 실제 수행에 의해서 설정됩니다. 그러나 필요한 경우에 
  강제로 설정할 수 있습니다. 

\

- 이 함수의 사용과 호출에 있어, 제공된 ㈜커미조아의 함수 헤더 Visual Basic 에서는 함수의
  첨두어 cml 가 붙지 않습니다.


PARAMETER
`````````````

▶ BoardID : 사용자가 설정한 디바이스(보드) ID. 
 
▶ NodeId : 사용자가 제어하고자 하는 노드 번호.  
 
▶ Channel : 축 번호. 통합 축으로 관리되는 축 번호를 의미하며, 상수 값으로 0 (Zero Based) 이상, 최대 
통합 축 개수 - 1 이하의 값을 축 번호로 설정할 수 있습니다. 
 
▶ IsSuccess : cmlPmHomeGetSuccess() 함수의 인자이며, 이 함수가 호출된 시점을 기준으로 이전에 
원점복귀가 성공적으로 완료된 상태인지를 알려 주는 매개 변수입니다.

  .. csv-table::
   :widths: 10 90
   :header-rows: 1
   :stub-columns: 0

    Value, Meaning
    0(cmlFALSE), 지정한 축을 원점 복귀 이송이 진행 중인 상태 혹은 비정상적으로 완료된 상태로 설정합니다.
    1(cmlTRUE), 지정한 축을 원점 복귀 이송이 정상적으로 완료된 상태로 설정합니다.


RETURN VALUE
`````````````

.. csv-table::
  :widths: 10 90
  :header-rows: 1
  :stub-columns: 0

  Value, Meaning
  음수, 수행 실패
  ERR_NONE, 수행 성공

REFERENCE
`````````````

- 원점복귀의 성공 여부에 대한 플래그 값은 응용프로그램이 종료(終了)되어도 그대로  
  유지됩니다. 따라서 다시 응용프로그램이 시작되면 이전에 원점복귀를 정상적으로 
  수행했었는지를 알 수가 있습니다. 단, PC의 하드웨어적인 전원이 차단되거나 재 
  시작(Rebooting) 되면 그 값은 FALSE로 리셋됩니다. 따라서 cmlPmHomeGetSuccess() 함수의 
  이러한 특성(特性)을 활용하면 프로그램이 종료되었다가 다시 실행될 때 이전의 원점복귀 
  수행여부를 확인(確認)할 수가 없어서 매번 원점복귀를 수행해야 했던 불편을 보완(補完)할 
  수 있습니다. 

\

- IsSuccess 매개 변수(媒介變數)가 FALSE인 경우는 원점복귀가 진행중인 경우를 의미할 
  수도 있고 비정상적으로 종료되었음을 의미할 수도 있습니다. 따라서 cmlPmHomeMoveStart() 
  함수를 사용한 경우에는 먼저 cmlPmHomeIsBusy() 함수나 cmlPmHomeWaitDone() 함수를 선행하여 
  완료를 확인(確認)한 후에 cmlPmHomeGetSuccess()를 사용하여 성공여부를 확인(確認)하는 것이 
  정석입니다.

\

- 이전에 원점복귀가 성공적으로 수행되었더라도 해당 축의 원점복귀를 다시 시작하면 
  원점복귀의 성공 여부에 대한 플래그는 FALSE로 리셋(Reset)됩니다. 

EXAMPLE
```````````````````

.. code-block:: c++
 :linenos:
 :emphasize-lines: 5

  C/C++ 
  #include “ComiMLink2_SDK.h” 
  #include “ComiMLink2_SDK_Def.h” 
  long BoardID = 0; 
  /* 0번 축에 대하여 원점 복귀 이송을 시작하고, 진행 상태를 확인한 후 완료 여부를 확인합니다. */ 
  long nIsHomming = cmlTRUE; 
  cmlPmHomeMoveStart(BoardID, 0, ccmlX1 ); 
  while( nIsHomming ) 
  { 
  //원점 복귀 진행 여부를 확인합니다. 
  cmlPmSxWaitDone(BoardID, 0, ccmlX1, &nIsHomming ); 
  } 
  long nIsSuccess = cmlFALSE; 
  //원점 복귀 성공 여부를 확인합니다. 
  cmlPmHomeGetSuccess(BoardID, 0, ccmlX1, &nIsSuccess ); 
  if( nIsSuccess ) 
  {cmlMODE_SC 
  MessageBox( "Home return success", "Message", MB_OK ); 
  } 
  else 
  { 
  OutputDebugString( "Home return fail!" ); 
  }